Agents: a companion per agent, <agent>.prebuilt.restate, and the agent's own contexts - #311

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

`answer_once` no longer publishes after each commit of a turn's steps:
`chat_turn` records what follows a commit (`after_steps`, a per-attempt
scope value, set only for a followed turn), and `answer_once` hands it to
`Conversation.hold` as an opaque callback, after forgetting the calls whose
results the commit stored (`settled`, which no longer rides on a publish).
So a plain session object's handler that prompts stores its turn and makes
no publish nor companion lookup.

`publish` from a context with no companion now raises (`companion_in`)
instead of silently skipping. Waiting for a signal (`wait_for_signal`,
`wait_for`, LangGraph's interrupts and `nodes.wait_for_signal`) from a plain
session object fails with a terminal error that says to use an agent,
instead of a TypeError that Restate retried forever.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

The conversation stores; the agent's chat turn publishes; a handler of your
own that prompts stores its turn and publishes nothing; waits and steering
need an agent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

…ommit

- Every handler of an `AgentObject` (not only `chat`) has the steps its
  turns store publish, through `publish_steps`, as before 8f7ad14: a
  handler you add that prompts publishes each committed step again (no
  start nor close: only `chat` is a turn in the companion). A background
  agent's publish nothing, as before.
- `publish` no longer forgets settled calls: `answer_once` does it once
  per commit, before what follows it; the `settle` handler publishes
  outside any turn, where it did nothing.
- Tests: LangGraph's `nodes.wait_for_signal` and `interrupt()` from a
  plain session object fail the turn terminally with the needs-agent
  message.
- resurrect.py: re-point `pydantic-denial-approves` at today's
  `approval_of`; it is caught by three tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

…in TypeScript

`needs_agent` now raises `NeedsAgent`, a `TerminalError` that `Tool.run`
(and Pydantic AI's tool error hook) never turns into the tool's result for
the model: every wait from a session object that is no agent, the signal
tool included, fails the turn once, for good, closed `failed`. A tool's
other terminal errors still go to the model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

A turn that runs in a handler other than `chat`, on an agent object,
published after each commit of its steps but never at the end: a follower
saw the steps arrive and then heard nothing, because only `chat_turn` calls
the companion's `close`, which is what wakes followers as a `chat` turn
ends.

It now publishes once more, after the commit that stores the turn's answer,
never before it: a follower told earlier would read a conversation that has
no answer yet. A turn closed for good (failed, refused, stopped) publishes
its end too, since its close stores the turn's answer; a turn whose attempt
failed publishes none, as it has not ended and the next attempt carries it
on. A turn nobody follows (a background agent's) publishes neither its steps
nor its end, as before.

The seam is `after_answer`, beside `after_steps`: every handler of an
`AgentObject` sets it (`publish_end`, guarded by the same `_unfollowed`
check as `publish_steps`), and `answer_once` runs it as an opaque callback
once the answer is stored. A `chat` turn sets nothing there: its end is the
companion's `close`, which publishes its last change with it, so its
publishes are what they were (`start`, one per commit of its steps,
`close`) and it gains no round trip.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

…s `signals`

Both SDKs ship one `signals` object for a whole endpoint, keyed
`<agent>:<key>`. A cluster has one service of that name, so a Python
endpoint and a TypeScript endpoint registered against it take the name
from each other: one SDK's companion then serves the other's agents.

The design note records the move to one object per agent, named
`<agent>.prebuilt.restate` and keyed as the agent: why the shared name
cannot stay, why the marker is a suffix, that only agents have one, what
the rename touches in both repos, how a deployment on `signals` migrates
(drain first; the revision restarts per key), and what must hold
afterwards.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

The shared `signals` and `<agent>.agentprebuilt.restate` are both preview,
and neither per-agent companion has been released: the new object starts
empty for every key, and what a running `signals` holds is dropped with
it. The conversation is untouched either way, since the companion holds
none of it.

So the note drops the upgrade path, with the alias and the revision
tolerance it asked for.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

An agent's companion is already its own object, keyed as the agent: the
name is what is left to settle. `agent` in the suffix says nothing the
agent's own name does not, so the marker is `.prebuilt.restate`, and an
agent's companion is as unique as the agent itself.

Restate refuses names that start with `restate`, so it stays a suffix.
The design note keeps the old spelling where it describes what came
before.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

The script still counted a service named `signals` as a companion, for the
object every agent shared before. Nothing serves it any more.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

An agent's APIs and a session object's take the same context today, so a
handler reaching up a layer — a signal wait from a plain session object —
is only found out while the turn runs.

The note names the two contexts, as protocols in Python with a marker
that never exists at runtime and as plain `extends` in TypeScript: a
signpost in the signature, with `NeedsAgent` left as the guard that
actually stops the wait.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

An agent's handler and a session object's take the same context, so a
handler that reaches up a layer is only found out while the turn runs.
The two protocols extend the session contexts with a private marker that
is declared and never present, so a plain session context is not one of
them for a type checker, and the layer is in the signature where the
person writing the handler reads it.

Nothing of them exists at runtime: the session tier goes on building its
attempt contexts, nothing reads the marker, and `NeedsAgent` stays the
guard that stops a wait from a session object.

What takes them is the agent's own surface: `chat`'s `answer` and the
bound it is registered under, the built-in views, the private handlers,
and what only an agent does with a context, which reaches its companion
(`chat_turn`, `publish` and the publishes around a turn, `cleared`).

The tier below keeps `SessionContext`, and that is wider than the design
note's table says. A plain session object drives the conversation: the
tests register `answer_once` on one, and each framework's `prompt` is
documented for a handler of your own and takes a session context, so
`answer_once`, `settle` and `compact`, the turn's `settings_of` and
`stop_signal_of`, `take_steers`, `wait_for` and `companion_in` are all
reached from there and stay as they are. The langgraph signal node and
the interrupt resume read their context from the run's, and guard it
with `waits_in`, which raises `NeedsAgent`: narrowing them would need a
cast that says the opposite of what the guard is for.

Two tests pass a plain context to `publish` on purpose, to show it still
raises; they now say so with a cast.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

The note's first draft asked for the conversation, the turn's helpers, the
signal waits and the langgraph nodes to take an agent's context. None of
them can: a handler of a plain session object drives `answer_once`, each
framework's public `prompt` funnels into it, and `companion_at` and
`waits_in` are the probes that find out which tier they are on. Narrowing
them is a type error in the SDK's own tests.

What narrowed is the agent's registration surface, which is the honest
reach of a name that is only a signpost. The note now says so, and says
why TypeScript, which is barred from nothing, holds the same line.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV